<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<meta name="author" content="Aurelio Jargas www.aurelio.net">
<META NAME="generator" CONTENT="http://txt2tags.org">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<LINK REL="stylesheet" TYPE="text/css" HREF="inc/site.css">
<TITLE>txt2tags tips</TITLE>
<link rel="icon" type="image/png" href="/favicon.png">
</HEAD>
<BODY id="tips">

<DIV CLASS="header" ID="header">
<h1><a href="/">txt2tags</a></h1>
<H3>Tips &amp; Tricks</H3>
</DIV>

<DIV CLASS="body" ID="body">
<div id="sidebar">
Hot
  <ul>
  <li id="menuonline"><a href="./online.php">Txt2tags Online</a></li>
  <li id="menumarkup"><a href="./markup.html">Markup Demo</a></li>
  </ul>
About
  <ul>
  <!-- <li id="menuhome"><a href="/">Home</a></li> -->
  <li id="menufeatures"><a href="./features.html">Features</a></li>
  <li id="menusample"><a href="./sample.html">Example</a></li>
  <li id="menushots"><a href="./shots.html">Screenshots</a></li>
  <li id="menudocs"><a href="./docs.html">Documentation</a></li>
  <li id="menutips"><a href="./tips.html">Tips &amp; Tricks</a></li>
<!--
  <li id="menuoldnews"><a href="./misc/oldnews.html">Old News</a></li>
-->
  </ul>
Code
  <ul>
  <li id="menudownload"><a href="./download.html">Download</a></li>
  <li id="menuchangelog"><a href="./changelog.html">Changelog</a></li>
  <li id="menutools"><a href="./tools.html">Tools</a></li>
  <li><a href="http://bugs.txt2tags.org">Bug tracker</a></li>
  <li><a href="http://svn.txt2tags.org">SVN</a></li>
  </ul>
Community
  <ul>
  <li id="menuwiki"><a href="http://wiki.txt2tags.org">Wiki</a></li>
  <li id="menublog"><a href="http://txt2tags.wordpress.com">Blog</a></li>
  <li id="menuteam"><a href="./team/index.html">The Team</a></li>
  <li id="menuchildren"><a href="./children.html">The Children</a></li>
  <li id="menucomments"><a href="http://txt2tags.wordpress.com/user-comments/">User Comments</a></li>
  <li id="menuart"><a href="./art.html">Artwork</a></li>
  </ul>
Social
  <ul>
  <li id="menuml"><a href="./ml.html">Mailing List</a></li>
  <li><a href="http://www.facebook.com/pages/txt2tags/335201827209">Facebook</a></li>
  <li><a href="http://twitter.com/aureliojargas">twitter</a></li>
  <!-- <li><a href="http://www.orkut.com.br/Main#Community?cmm=87935">Orkut</a></li> -->
  <li><a href="http://identi.ca/group/txt2tags">identi.ca</a></li>
  </ul>

<P>
<A HREF="https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&amp;business=verde%40aurelio%2enet&amp;item_name=txt2tags%20donation&amp;no_shipping=1&amp;return=http%3a%2f%2faurelio%2enet%2fdonate%2dthanks%2ehtml&amp;cn=&amp;tax=0&amp;currency_code=USD&amp;bn=PP%2dDonationsBF&amp;charset=UTF%2d8"><IMG ALIGN="middle" SRC="img/donate.png" BORDER="0" alt="DONATE"></A>
</P>
</div>
<DIV CLASS="toc">

  <UL>
  <LI><A HREF="#general">General</A>
    <UL>
    <LI>1. <A HREF="#top-mistakes">Top 4 user mistakes</A>
    <LI>2. <A HREF="#doc-tree">Quick document tree</A>
    <LI>3. <A HREF="#strike">Make strike text</A>
    <LI>4. <A HREF="#filter-icase">Make case insensitive filters</A>
    <LI>5. <A HREF="#center-para">Make centred aligned paragraphs</A>
    <LI>6. <A HREF="#link-bank">Use a link bank to keep your text clean</A>
    <LI>7. <A HREF="#auto-link">Use automatic linking for "cristal clear" text</A>
    <LI>8. <A HREF="#force-url">Force link (URL) recognition</A>
    <LI>9. <A HREF="#image-unicode">Use spaces and Unicode characters in image filename</A>
    <LI>10. <A HREF="#date-default-format">Change the default format for the %%date macro</A>
    <LI>11. <A HREF="#code-syntax">Make code snippets colored (syntax highlight)</A>
    <LI>12. <A HREF="#copyright-symbol">Insert copyright symbols: © ® &#8482;</A>
    <LI>13. <A HREF="#dump-config">Config overview (or Solving configuration problems)</A>
    </UL>
  <LI><A HREF="#target-specific">Target Specific</A>
    <UL>
    <LI>14. <A HREF="#col-align">Table COLUMN align targets: SGML, LaTeX and Man Page</A>
    <LI>15. <A HREF="#css-sugar">(X)HTML: What exactly the --css-sugar option does</A>
    <LI>16. <A HREF="#html-line-break">(X)HTML: Insert a manual line break &lt;BR&gt;</A>
    <LI>17. <A HREF="#html-semantic-tags">(X)HTML: Use semantic tags (STRONG, EM, INS, DEL) instead visual tags (B, I, U, S)</A>
    <LI>18. <A HREF="#html-super-sub">(X)HTML: Make subscript/superscript text</A>
    <LI>19. <A HREF="#html-remote-image">(X)HTML: Use a remote image</A>
    <LI>20. <A HREF="#html-img-alt">(X)HTML: Insert text for images ALT attribute</A>
    <LI>21. <A HREF="#html-custom-tags">(X)HTML: Insert custom tags (DIV, SPAN)</A>
    <LI>22. <A HREF="#html-entities">(X)HTML: Use entities like &amp;eacute; for accented characters</A>
    <LI>23. <A HREF="#html-custom-tags">(X)HTML: Split the page in multiple files</A>
    <LI>24. <A HREF="#html-to-t2t">(X)HTML: Convert HTML pages to the txt2tags markup</A>
    <LI>25. <A HREF="#man-section">Man: Change section number</A>
    <LI>26. <A HREF="#man-options">Man: Make the OPTIONS part of the man page</A>
    <LI>27. <A HREF="#mgp-pause">MagicPoint: Make a pause on the slide</A>
    <LI>28. <A HREF="#tex-style">LaTeX: Load extra packages (\usepackage)</A>
    <LI>29. <A HREF="#tex-date">LaTeX: Remove the current date</A>
    <LI>30. <A HREF="#tex-lang">LaTeX: Set the language config (babel, inputenc)</A>
    <LI>31. <A HREF="#tex-user-style">LaTeX: Use a personal style file (.sty)</A>
    <LI>32. <A HREF="#tex-greek">LaTeX: Use symbols and Greek letters (µ « ® Ø)</A>
    </UL>
  <LI><A HREF="#text-editors">Text Editors</A>
    <UL>
    <LI>33. <A HREF="#vim-convert">Vim: Convert the current file</A>
    <LI>34. <A HREF="#vim-mappings">Vim: Handy mappings to convert files</A>
    </UL>
  </UL>

</DIV>
<P>
<A HREF="http://txt2tags.wordpress.com/2006/09/21/new-hot-document-tips-tricks/">Suggest a new tip!</A>
</P>

<H1 ID="general">General</H1>

<H2 ID="top-mistakes">1. Top 4 user mistakes</H2>

<OL>
<LI>Forget to close lists with <B>two</B> blank lines (or with an empty
item)
<PRE>
<b>BAD</b>                           <b>GOOD</b>
- My cool list                - My cool list
- Should end here             - Ends here

= No, not a title =
                              = Title =
</PRE>

<LI>Forget to "glue" the marks with their contents, leaving unwanted spaces
<PRE>
<b>BAD</b>                           <b>GOOD</b>
** not bold**                 **bold**
__not underline __            __underline__
// no way it is italic //     //italic//
[invalid link ]               [label link]
[ invalid_image.png ]         [image.png]
</PRE>

<LI>Forget to add the required spaces around table cells
<PRE>
<b>BAD</b>                           <b>GOOD</b>
|no|it's|not|a|table|         | this | is | a | table |
</PRE>

<LI>Forget to add leading spaces to identify nested lists
<PRE>
<b>BAD</b>                           <b>GOOD</b>
: definition list             : definition list 
- turned to bullet list?        - bullet inside
+ and now it is numbered?         + numbered inside bullet
- what a mess!                  - back to bullet
</PRE>

</OL>

<H2 ID="doc-tree">2. Quick document tree</H2>

<P>
Writing a long document and suddenly get lost? Needs to edit that 50
page monster you don't touch for months? There is a quick way to get
an overview of the contents:
</P>

<PRE>
$ <b>txt2tags --toc-only -t txt userguide.t2t</b>
  Part I - Introducing Txt2tags
    The First Questions You May Have
    Supported Formatting Structures
    Supported Targets
    Status of Supported Structures by Target
    The Three User Interfaces: Gui, Web and Command Line
  Part II - OK, I want it. Now what?
    Download &amp; Install Python
    Download txt2tags
    ...
</PRE>

<P>
The <CODE>--toc-only</CODE> option dumps the Table of Contents of the document,
using the same target as the document's. So we force it to be clear
text with <CODE>-t txt</CODE>. Another option that can be used is
<CODE>--enum-title</CODE> to get nice numbers:
</P>

<PRE>
$ <b>txt2tags --toc-only -t txt --enum-title userguide.t2t </b>
  1. Part I - Introducing Txt2tags
    1.1. The First Questions You May Have
    1.2. Supported Formatting Structures
    1.3. Supported Targets
    1.4. Status of Supported Structures by Target
    1.5. The Three User Interfaces: Gui, Web and Command Line
  2. Part II - OK, I want it. Now what?
    2.1. Download &amp; Install Python
    2.2. Download txt2tags
    ...
</PRE>

<P>
If the document tree is deep, you can limit the dump to any level with the <CODE>--toc-level</CODE> option:
</P>

<PRE>
$ <b>txt2tags --toc-only -t txt --enum-title --toc-level 1 userguide.t2t </b>
  1. Part I - Introducing Txt2tags
  2. Part II - OK, I want it. Now what?
  3. Part III - Writing and Converting Your First Document
  4. Part IV - Mastering Txt2tags Concepts
  5. Part V - Mastering Marks
  6. Part VI - Mastering Macros
  7. Part VII - Mastering Settings
  8. Part VIII - Black Magic
  9. Part IX - Txt2tags HISTORY
</PRE>

<H2 ID="strike">3. Make strike text</H2>

<P>
Upgrade your txt2tags to version 2.5 or newer, which has strike text support with the <CODE>--</CODE> mark. For example, <CODE>--STRIKE--</CODE> becomes <s>STRIKE</s>.
</P>
<P>
In older versions, some nice filters will do the trick:
</P>

<PRE>
%%% Support for --strike-- text in txt2tags older than 2.5
%
%!postproc(html):  '--([^ ].*?)--'  &lt;s&gt;\1&lt;/s&gt;
%
%!style(tex): ulem
%!postproc(tex):  --(.*?)--  \sout{\1}
</PRE>

<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="filter-icase">4. Make case insensitive filters</H2>

<P>
<A HREF="userguide/PreProc.html">PreProc</A> and <A HREF="userguide/PostProc.html">PostProc</A> filters are case sensitive by default. This
means that when matching, the text "txt2tags" is different from
"TXT2TAGS". If you want to make a filter that treats lower and
uppercase letters as the same (ignore case), just put a "<CODE>(?i)</CODE>" at
the beginning. Example:
</P>

<PRE>
%preproc: '(?i)latex'   'LaTeX'   
</PRE>

<P>
This way, "latex", "LATEX", "LAtex" and all its variants will be
changed to "LaTeX".
</P>

<H2 ID="center-para">5. Make centred aligned paragraphs</H2>

<P>
In txt2tags you can't center paragraphs, but you can center a table.
So...
</P>

<PRE>
    | This is a centered paragraph.
</PRE>

<P>
This line results in:
</P>

<TABLE ALIGN="center">
<TR>
<TD>This is a centered paragraph.</TD>
</TR>
</TABLE>

<P>
<B>Note:</B> There are spaces before the pipe <CODE>|</CODE> to make the table centred. There
are no trailing pipe at the end of the line, so this table has no
border, making it invisible.
</P>
<P>
<B>Note:</B> Yes, this is ugly and piggy. Avoid to use it.
</P>
<P>
<B>Note:</B> In (X)HTML targets, it's best to
<A HREF="#html-custom-tags">enclose the paragraph inside a DIV</A> and make a CSS
rule to center it.
</P>

<H2 ID="link-bank">6. Use a link bank to keep your text clean</H2>

<P>
If your document will use many links (URLs), the text can quickly become too
noisy and polluted. The cleaner approach is to store all the links at
the <A HREF="userguide/ConfigArea.html">config area</A>, making a link bank:
</P>

<PRE>
%!preproc: URLT2T    http://txt2tags.org
%!preproc: URLGOOGLE http://google.com?q=txt2tags+is+cool
%!preproc: URLBLOG   http://myblog.wordpress.com/2006/10/31/foo-bar-baz
</PRE>

<P>
Then you can write your text with cleaner links:
</P>

<PRE>
This site is powered by [txt2tags URLT2T]. For more information
please [read my Blog URLBLOG] or [search Google URLGOOGLE].
</PRE>

<P>
Compare this to the inline links (ugly) version:
</P>

<PRE>
This site is powered by [txt2tags http://txt2tags.org].
For more information please
[read my Blog http://myblog.wordpress.com/2006/10/31/foo-bar-baz]
or [search Google http://google.com?q=txt2tags+is+cool].
</PRE>

<P>
<B>Plus:</B> If there are links that you use all the time in your
documents (your website or blog, for example), you can make a global
link bank on an urls.t2t file, or on your
<A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>, then
all your documents can use them. The other advantage is that it makes
easy when the link changes, you just have to edit one single place.
</P>

<H2 ID="auto-link">7. Use automatic linking for "cristal clear" text</H2>

<P>
An evolution from the previous tip, you can put links automatically
for any word(s) you want.
</P>

<PRE>
%!preproc: '(?i)(txt2tags)'   '[\1 http://txt2tags.org]'
%!preproc: '(Google)'         '[\1 http://google.com]'
%!preproc: '(Yahoo! Groups)'  '[\1 http://groups.yahoo.com]'
</PRE>

<P>
Then in your text you won't bother inserting links manually, txt2tags
will do it for you:
</P>

<PRE>
I do use Txt2tags, Google and Yahoo! Groups everyday.
</PRE>

<P>
Converting this text to XHTML:
</P>

<PRE>
&lt;p&gt;
I do use &lt;a href="http://txt2tags.org"&gt;Txt2tags&lt;/a&gt;,
&lt;a href="http://google.com"&gt;Google&lt;/a&gt; and
&lt;a href="http://groups.yahoo.com"&gt;Yahoo! Groups&lt;/a&gt; everyday.
&lt;/p&gt;
</PRE>

<P>
Handy, huh? Note that the "<CODE>(?i)</CODE>" part on the first filter make it
<A HREF="#filter-icase">case insensitive</A>, working for "txt2tags", "TXT2TAGS"
and any other variant.
</P>

<H2 ID="force-url">8. Force link (URL) recognition</H2>

<P>
When trying (and failing) to make some funky links like:
</P>

<PRE>
[Main page index.php?page=main]

[Product details product?id=1234567]
</PRE>

<P>
Just "protect" the link address with the raw mark and it will be converted correctly:
</P>

<PRE>
[Main page ""index.php?page=main""]

[Product details ""product?id=1234567""]
</PRE>

<P>
<B>Note:</B> This is often needed for local (relative) links only. Full URLs like <A HREF="http://www.example.com/product?id=1234567">www.example.com/product?id=1234567</A> are recognized by default.
</P>

<H2 ID="image-unicode">9. Use spaces and Unicode characters in image filename</H2>

<P>
We need to be restrictive to avoid false positives when matching texts. These are the currently allowed characters for an image filename:
</P>

<PRE>
A-Za-z0-9_,.+%$#@!?+~/-
</PRE>

<P>
If your image filename contains spaces, accented letters or Unicode characters, just protect the filename (except the extension!) with the raw mark:
</P>

<PRE>
[""image中文"".jpg]
</PRE>

<H2 ID="date-default-format">10. Change the default format for the %%date macro</H2>

<P>
When used without arguments, the <A HREF="userguide/date.html">%%date macro</A> expands to the current date in the ISO format: <CODE>YYYYMMDD</CODE>. But with a nice filter, you can change this default format:
</P>

<PRE>
%!preproc:  %%date  %%date(%d-%m-%Y %H:%M)
</PRE>

<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="code-syntax">11. Make code snippets colored (syntax highlight)</H2>

<P>
Txt2tags doesn't colorize programming code inside verbatim blocks.
That would be plain bloat, and we're KISS.
</P>
<P>
But you can make that using any other colorizer program and save the
results to a file. Then you just include this file on the txt2tags
conversion using the <A HREF="userguide/includecommand.html">Tagged Include</A>
feature.
</P>

<PRE>
%!include(html): ''colorized-file.py.html'' 
</PRE>

<P>
If you use the <A HREF="http://vim.org">Vim editor</A>, just run this command to
get you code colorized in HTML (check the path for 2html.vim on your
system):
</P>

<PRE>
vi -c "so /usr/share/vim/vim7/syntax/2html.vim|wqa" file.py
</PRE>

<H2 ID="copyright-symbol">12. Insert copyright symbols: © ® &#8482;</H2>

<P>
You can enter the © and ® symbols directly on the source file without fuss. Just find out how to insert them in your text editor. Copy &amp; paste also works fine (copy from here!).
</P>
	<BLOCKQUOTE>
	<B>Note:</B>
	In Vim, type <CODE>Ctrl-K Co</CODE> and <CODE>Ctrl-K Rg</CODE> in Insert mode.
	The :dig command lists other symbols.
	</BLOCKQUOTE>
<P>
Depending on the target, you may have to specify a new file encoding so that these symbols appear correctly. If you run into problems, try adding this line to your configuration:
</P>

<PRE>
%!encoding: iso-8859-1
</PRE>

<P>
The &#8482; symbol is a little trickier because it's part of the new UTF-8 encoding. First you need to save your source file as an UTF-8 text file. Check your text editor's preferences. Then just tell txt2tags about the new encoding:
</P>

<PRE>
%!encoding: utf-8
</PRE>

<P>
<B>Bonus Tip:</B> If you plan to type symbols or accented characters in your texts, a good practice is always use the UTF-8 encoding in your files. You don't need to understand exactly what it is, just keep in mind that is has all the symbols you may need someday :)
</P>
<P>
Another solution is to use the target's specific characters entities that represent those symbols. Then you can insert those symbols as "(C)", "(R)" and "(TM)" on the source file and let the filters do the dirty job. But remember that each target must have its own set of filters. An example for HTML:
</P>

<PRE>
% Filters to use (C), (R) and (TM) as copyright symbols
%!postproc(html):  \(C\)   &amp;copy;
%!postproc(html):  \(R\)   &amp;reg;
%!postproc(html):  \(TM\)  &amp;#8482;
</PRE>

<H2 ID="dump-config">13. Config overview (or Solving configuration problems)</H2>

<P>
In txt2tags you can
<A HREF="userguide/ConfigurationLoadingOrderandPrecedence.html">define configuration in three tiers</A>:
</P>

<UL>
<LI>The user configuration file (RC)
<LI>The source document <A HREF="userguide/ConfigArea.html">Config Area</A>
<LI>The command line options
</UL>

<P>
Things can get real wild if you make lots of configs in all those
places. Even wilder if you're using the
<A HREF="userguide/includeconfcommand.html">%!includeconf command</A>
to get more configuration to your document.
</P>
<P>
In doubt or trouble, use the <CODE>--dump-config</CODE> option to see all the
configuration that is being read. First it lists all the config found
on the RC file:
</P>

<PRE>
$ <b>txt2tags --dump-conf userguide.t2t</b>
RAW config for RC file
  (all)    target........: html
</PRE>

<P>
Then there is the config found on the document's <A HREF="userguide/ConfigArea.html">Config Area</A>. Note
that the first column shows the target where the config will be
applied. If it is "(all)", this config is valid for all targets.
</P>

<PRE>
RAW config for source document
  (all)    target........: html
  (all)    options.......: --toc --toc-level 2 --css-sugar
  (all)    options.......: --css-sugar --no-toc --style userguide.css
  (all)    postproc......: ('&lt;H3&gt;Aurelio, .*', '')
  (all)    preproc.......: ('IMGPATH', '.')
  ...
  (html)   preproc.......: ('^%nopdf', '')
  (html)   preproc.......: ('^ *--------*', '')
  (html)   preproc.......: ('^ *========*', '')
</PRE>

<P>
Next are the command line options:
</P>

<PRE>
RAW config for command line
  (all)    dump-config...: ON
  (all)    infile........: userguide.t2t
  (all)    realcmdline...: ['--dump-conf', 'userguide.t2t']
</PRE>

<P>
And after all this listing, here is the result: the parsed config.
It's the real configuration that will be applied to the document
after all the configs were read and processed.
</P>

<PRE>
Full PARSED config
           css-sugar.....: ON
           dump-config...: ON
           infile........: userguide.t2t
           realcmdline...: --dump-conf, userguide.t2t
           sourcefile....: userguide.t2t
           style.........: userguide.css
           target........: html
           toc-level.....: 2

Active filters
           preproc.......: IMGPATH  -&gt;  .
           preproc.......: MARKPROP  -&gt;  **Properties:**
           preproc.......: MARKCONT  -&gt;  **Contains:**
           ...
           preproc.......: ^%nopdf  -&gt;  
           preproc.......: ^ *--------*  -&gt;  
           preproc.......: ^ *========*  -&gt;  
           postproc......: &lt;H3&gt;Aurelio, .*  -&gt;  
</PRE>

<H1 ID="target-specific">Target Specific</H1>

<H2 ID="col-align">14. Table COLUMN align targets: SGML, LaTeX and Man Page</H2>

<P>
Some targets let you align each table cell independently, as HTML.
Other are more strict, just letting you align the table column, then
all its cells share the same positioning. This is the case for SGML,
LaTeX and Man.
</P>
<P>
On this targets, the column alignment is defined by the align of the
<B>first</B> table row cells (usually it's a title row). So keep that in
mind when writing your text.
</P>

<PRE>
  |     Name     |   Age   |
  | John Smith   |      55 |
  | Mary Katana  |      23 |
</PRE>

<P>
In this example, both columns will be centered on the aforementioned
targets, regardless the left and right align defined on the second and
third rows.
</P>

<H2 ID="css-sugar">15. (X)HTML: What exactly the --css-sugar option does</H2>

<P>
It "insert CSS-friendly tags for HTML and XHTML targets" ;)
</P>
<P>
Ok, ok, more details:
</P>

<UL>
<LI>The CELLPADDING attribute is removed from TABLE tag
<LI>The HR tags around Table of Contents (TOC) are removed
<LI>The Table of Contents is placed inside the new "toc" DIV
<LI>The page contents (except TOC) is placed inside the new "body" DIV
<LI>The PRE tag contents is not indented by two spaces
<LI>The headers (first three lines) are changed:
  <UL>
  <LI>They are placed inside the new "header" DIV
  <LI>They use H1, H2 and H3 tags with no formatting
  </UL>
</UL>

<P>
So this option clears the formatting attributes and create new DIVs to
make it easier to use CSS rules. Then you can see the page as a three
piece component: header, toc, body and apply different rules for each.
</P>
<P>
<B>Note:</B> Using <CODE>--style</CODE> doesn't imply <CODE>--css-sugar</CODE>. You have to
declare both.
</P>

<H2 ID="html-line-break">16. (X)HTML: Insert a manual line break &lt;BR&gt;</H2>

<P>
Txt2tags doesn't have a mark for the manual line break. In the cases
you want to use it, maybe a bullet list, a table or a verbatim text
would fit better.
</P>
<P>
But if the line break is the solution you want, just make your own new
mark for it. Let's say "@@" will be the line break mark.
</P>

<PRE>
%!postproc( html): @@ &lt;BR&gt;
%!postproc(xhtml): @@ &lt;br /&gt;
</PRE>

<P>
Then in your text, use @@ when you want a line break. Example:
</P>

<PRE>
First line @@ Second Line @@ Third line
</PRE>

<H2 ID="html-semantic-tags">17. (X)HTML: Use semantic tags (STRONG, EM, INS, DEL) instead visual tags (B, I, U, S)</H2>

<P>
By default txt2tags uses the good old visual tags (<CODE>&lt;B&gt;</CODE>, <CODE>&lt;I&gt;</CODE>, <CODE>&lt;U&gt;</CODE>, <CODE>&lt;S&gt;</CODE>) for bold, italic, underline and strike text.
</P>
<P>
Some people prefer to use their semantic equivalents (<CODE>&lt;strong&gt;</CODE>, <CODE>&lt;em&gt;</CODE>, <CODE>&lt;ins&gt;</CODE>, <CODE>&lt;del&gt;</CODE>) instead. If this is your case, just set up these filters:
</P>

<PRE>
% Use semantic tags (strong, em, ins, del) instead visual (B, I, U, S)
%!postproc(html):  '(?i)(&lt;/?)b&gt;'  '\1strong&gt;'
%!postproc(html):  '(?i)(&lt;/?)i&gt;'  '\1em&gt;'
%!postproc(html):  '(?i)(&lt;/?)u&gt;'  '\1ins&gt;'
%!postproc(html):  '(?i)(&lt;/?)s&gt;'  '\1del&gt;'
</PRE>

<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="html-super-sub">18. (X)HTML: Make subscript/superscript text</H2>

<P>
Txt2tags doesn't have a mark for subscript or superscript text.
But you can make your own. Let's define the following two new marks
for them:
</P>

<UL>
<LI><B><CODE>^^text^^</CODE></B> for superscript text
<P></P>
<LI><B><CODE>,,text,,</CODE></B> for subscript text
</UL>

<P>
Using the same idea from the previous tip, we make two filters:
</P>

<PRE>
% The ^ need to be escaped by \
%!postproc(html):  \^\^(.*?)\^\^  &lt;sup&gt;\1&lt;/sup&gt;
%!postproc(html):  ,,(.*?),,      &lt;sub&gt;\1&lt;/sub&gt;
</PRE>

<P>
Using this filters, <CODE>^^upper^^ and ,,lower,,</CODE> becomes
<CODE>&lt;sup&gt;upper&lt;/sup&gt; and &lt;sub&gt;lower&lt;/sub&gt;</CODE>.
</P>
<P>
Again, you can instead use the modern CSS powered version:
</P>

<PRE>
%!postproc(html):  \^\^(.*?)\^\^  &lt;span class="textsup"&gt;\1&lt;/span&gt;
%!postproc(html):  ,,(.*?),,      &lt;span class="textsub"&gt;\1&lt;/span&gt;

% On the CSS:
% .textsup { vertical-align: super }
% .textsub { vertical-align: sub   }
</PRE>

<P>
If you want to use this filters for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="html-remote-image">19. (X)HTML: Use a remote image</H2>

<P>
In txt2tags you have a mark for local images, but not for remote ones.
The trick here is to fool the program making it think your remote
image is local.
</P>
<P>
There are two ways of achieving this. The first uses a filter:
</P>

<PRE>
%!postproc(html):  RemoteImage.jpg  http://www.example.com/myimage.jpg

Hi, check out my picture: [RemoteImage.jpg].
</PRE>

<P>
So txt2tags will make the image tag <CODE>&lt;IMG SRC="RemoteImage.jpg"&gt;</CODE>
and the filter will change it to <CODE>&lt;IMG SRC="http://www.example..."&gt;</CODE>.
</P>
<P>
The other trick is cleaner to type, but relies on a txt2tags behavior
that may not work on future versions. Just protect the image address
with the <A HREF="userguide/RawRawLineRawArea.html">raw mark</A>, from the
beginning to the last character before the dot:
</P>

<PRE>
Hi, check out my picture: [""http://www.example.com/myimage"".jpg].
</PRE>

<P>
Easy!
</P>

<H2 ID="html-img-alt">20. (X)HTML: Insert text for images ALT attribute</H2>

<P>
Txt2tags already puts an empty ALT="" attribute on all images, so all
you have to do is to fill it. <A HREF="userguide/PostProc.html">PostProc</A> comes for the rescue.
</P>

<PRE>
%!postproc(xhtml): '(?i)(city.jpg.*?alt=")'   '\1this is my city' 
%!postproc(xhtml): '(?i)(beach.jpg.*?alt=")'  '\1a really nice beach' 

Hello, this is a photo of my city: [city.jpg]
And this the beach near here: [beach.jpg]
</PRE>

<P>
This will be converted to:
</P>

<PRE>
&lt;p&gt;
Hello, this is a photo of my city:
&lt;img align="right" src="city.jpg" border="0" alt="this is my city"/&gt;
And this the beach near here:
&lt;img align="right" src="beach.jpg" border="0" alt="a really nice beach"/&gt;
&lt;/p&gt;
</PRE>

<P>
The <A HREF="userguide/PostProc.html">PostProc</A> rule is a
<A HREF="http://en.wikipedia.org/wiki/Regular_expression">regular expression</A>
that matches from the image filename until its ALT attribute contents
start. Don't worry if you don't understand these symbols. Just copy &amp;
paste these lines to you text and change "<B>city.jpg</B>" by your image
filename and "<B>this is my city</B>" to the image's text. The rest remains
untouched.
</P>

<H2 ID="html-custom-tags">21. (X)HTML: Insert custom tags (DIV, SPAN)</H2>

<P>
From txt2tags version 2.6 and newer, there's a new tagged mark to
directly insert target code.
</P>
<P>
You can do it in blocks:
</P>

<PRE>
'''
&lt;div id="mycooldiv"&gt;
	This paragraph will live inside mycooldiv DIV.

	But note that txt2tags marks are not interpreted here.
&lt;/div&gt;
'''
</PRE>

<P>
In specific lines:
</P>

<PRE>
''' &lt;div id="mycooldiv"&gt;

This paragraph will live inside mycooldiv DIV.

Txt2tags marks are interpreted here.

''' &lt;/div&gt;
</PRE>

<P>
Or even inline, inside a paragraph:
</P>

<PRE>
My name is ''&lt;span class="name"&gt;''John''&lt;/span&gt;''.
</PRE>

<P>
If you're using and older version of txt2tags, follow these tips:
</P>
<P>
You can combine the <A HREF="userguide/RawRawLineRawArea.html">Raw Line mark</A>
and a <A HREF="userguide/PostProc.html">PostProc</A> filter to insert any arbitrary (X)HTML tag you need.
</P>
<P>
First, decide which symbols you'll use to represent the <CODE>&lt;</CODE> and
<CODE>&gt;</CODE> characters. A popular choice is <CODE>{{</CODE> and
<CODE>}}</CODE>. Then write your tags inside Raw Lines and it will work.
Example:
</P>

<PRE>
%!postproc(html):  {{(.*?)}}  &lt;\1&gt;

""" {{div id="mycooldiv"}}
This paragraph will live inside mycooldiv DIV.

""" {{/div}}
</PRE>

<P>
This will generate the following HTML code:
</P>

<PRE>
&lt;div id="mycooldiv"&gt;
&lt;P&gt;
This paragraph will live inside mycooldiv DIV.
&lt;/P&gt;
&lt;/div&gt;
</PRE>

<P>
<B>Note:</B> The blank line after the paragraph is to make sure it will be closed before the DIV. If omitted, you'll end with tag overlap: <CODE>&lt;div&gt;&lt;p&gt;&lt;/div&gt;&lt;/p&gt;</CODE>.
</P>

<H2 ID="html-entities">22. (X)HTML: Use entities like &amp;eacute; for accented characters</H2>

<P>
All modern browsers know how to handle accented characters, you don't need to use HTML entities like <CODE>&amp;eacute;</CODE> or <CODE>&amp;atilde;</CODE> to represent them. Just type the accented letters normally.
</P>
<P>
The only thing you need to do, is to specify the correct encoding of your source file. You can use the txt2tags <CODE>--encoding</CODE> option or <CODE>%!encoding</CODE> directive. Examples:
</P>

<PRE>
% My source file is encoded in UTF-8
%!encoding: UTF-8

% My source file is encoded in latin-1 (ISO-8859-1)
%!encoding: iso-8859-1
</PRE>

<P>
If you really need the entities, for some exotic reason or system limitation, you can convert the accented chars using filters. If you use just a few accented chars, create one filter for each letter (lower and uppercase):
</P>

<PRE>
% Convert accented chars to HTML entities: é -&gt; &amp;eacute;
%!postproc(html):  á   &amp;aacute;
%!postproc(html):  â   &amp;acirc;
%!postproc(html):  à   &amp;agrave;
%!postproc(html):  ã   &amp;atilde;
%!postproc(html):  ä   &amp;auml;
%!postproc(html):  Á   &amp;Aacute;
% ...
</PRE>

<P>
If you want a general solution for all accented vowels plus C-cedilla and N-tilde, use this set of filters:
</P>

<PRE>
% Convert accented vowels (plus Ç and Ñ) to HTML entities
%!postproc(html):  ([ÁÉÍÓÚáéíóú])   &amp;\1acute;
%!postproc(html):  ([ÀÈÌÒÙàèìòù])   &amp;\1grave;
%!postproc(html):  ([ÄËÏÖÜäëïöü])   &amp;\1uml;
%!postproc(html):  ([ÂÊÎÔÛâêîôû])   &amp;\1circ;
%!postproc(html):  ([ÃÕãõ])         &amp;\1tilde;
%!postproc(html):  &amp;[ÁÀÃÄÂ](\w+;)   &amp;A\1
%!postproc(html):  &amp;[áàãäâ](\w+;)   &amp;a\1
%!postproc(html):  &amp;[ÉÈËÊ](\w+;)    &amp;E\1
%!postproc(html):  &amp;[éèëê](\w+;)    &amp;e\1
%!postproc(html):  &amp;[ÍÌÏÎ](\w+;)    &amp;I\1
%!postproc(html):  &amp;[íìïî](\w+;)    &amp;i\1
%!postproc(html):  &amp;[ÓÒÖÔÕ](\w+;)   &amp;O\1
%!postproc(html):  &amp;[óòöôõ](\w+;)   &amp;o\1
%!postproc(html):  &amp;[ÚÙÜÛ](\w+;)    &amp;U\1
%!postproc(html):  &amp;[úùüû](\w+;)    &amp;u\1
%!postproc(html):  Ñ                &amp;Ntilde;
%!postproc(html):  ñ                &amp;ntilde;
%!postproc(html):  Ç                &amp;Ccedil;
%!postproc(html):  ç                &amp;ccedil;
</PRE>

<P>
If you want to use this filters for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="html-custom-tags">23. (X)HTML: Split the page in multiple files</H2>

<P>
All you have to do is to normally convert your file to (X)HTML with
txt2tags, then use the excellent HTMLDOC tool to split it. Example:
</P>

<PRE>
htmldoc -t htmlsep -o output-folder file.html
</PRE>

<P>
You can get full instructions on how to install and use HTMLDOC with
txt2tags on
<A HREF="http://txt2tags.wordpress.com/2006/08/31/split-html-in-multiple-pages/">this Blog post</A>.
</P>

<H2 ID="html-to-t2t">24. (X)HTML: Convert HTML pages to the txt2tags markup</H2>

<P>
If you're migrating your site to txt2tags, there's a handy Vim script to convert all your HTML files to the simple t2t markup.
</P>

<UL>
<LI>First download the <A HREF="tools/unhtml.vim">unhtml.vim</A> script, or get it from the txt2tags "extras" folder.
<P></P>
<LI>Then open one HTML file on the <A HREF="http://www.vim.org">Vim editor</A> and execute the following command:

<PRE>
:source /path/to/unhtml.vim
</PRE>

<P></P>
<LI>A new txt2tags file named <CODE>&lt;yourfile&gt;.html.t2t</CODE> will be saved. Check its contents and correct by hand any mistake.
</UL>

<P>
Repeat this process to all your HTML files.
</P>
<P>
<B>Tip inside the tip:</B> You can comment line 85 if you want the script to preserve unknown tags. They are deleted by default. Just add a double quote at the line start:
</P>

<PRE>
" mmmmm, dangerous! it removes all remaining HTML tags
" %s,&lt;[^&gt;]*&gt;,,ge
</PRE>

<P>
<B>Note:</B> The Vim editor is installed by default on Linux and Mac OS X. Windows users must download and install it to use this script.
</P>

<H2 ID="man-section">25. Man: Change section number</H2>

<P>
By default txt2tags generates man pages for section 1 (user commands).
But your man page can use any of these sections:
</P>

<TABLE ALIGN="center" BORDER="1">
<TR>
<TH>Nr.</TH>
<TH>Topic</TH>
</TR>
<TR>
<TD ALIGN="center">1</TD>
<TD>Commands available to users</TD>
</TR>
<TR>
<TD ALIGN="center">2</TD>
<TD>Unix and C system calls</TD>
</TR>
<TR>
<TD ALIGN="center">3</TD>
<TD>C library routines for C programs</TD>
</TR>
<TR>
<TD ALIGN="center">4</TD>
<TD>Special file names</TD>
</TR>
<TR>
<TD ALIGN="center">5</TD>
<TD>File formats and conventions for files used by Unix</TD>
</TR>
<TR>
<TD ALIGN="center">6</TD>
<TD>Games</TD>
</TR>
<TR>
<TD ALIGN="center">7</TD>
<TD>Word processing packages</TD>
</TR>
<TR>
<TD ALIGN="center">8</TD>
<TD>System administration commands and procedures</TD>
</TR>
</TABLE>

<P>
To change the man section number, use this <A HREF="userguide/PostProc.html">PostProc</A> filter:
</P>

<PRE>
%!postproc(man): "^(\.TH.*) 1 "  "\1 5 "
</PRE>

<P>
Change the number "5" to the desired section number. Attention to the white spaces. Cut &amp; paste this line to make sure it is correct.
</P>
<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="man-options">26. Man: Make the OPTIONS part of the man page</H2>

<P>
Man pages use a standard format to show a program's options. You can
make your man page looks exactly as the system's pages using
definition lists. Pay attention to the bold marks and leading spacing
on each definition term. Example:
</P>

<PRE>
= OPTIONS =

:      **--dump-config**
print all the config found and exit

:  **-h**, **--help**
print help information and exit

:  **-V**, **--version**
print program version and exit
</PRE>

<H2 ID="mgp-pause">27. MagicPoint: Make a pause on the slide</H2>

<P>
You can use the strong bar (<CODE>=========</CODE>) to make a pause on the
current slide in MagicPoint. It's useful to show just the first part
of the slide, then you explain it, then you press the space bar and the
rest of the slide appears.
</P>
<P>
You can use as many pauses as needed, like one for each list item.
Example:
</P>

<PRE>
= My nice slide =

- Item one
====================
- Item two
====================
- Item three
====================
- Item four
-
</PRE>

<H2 ID="tex-style">28. LaTeX: Load extra packages (\usepackage)</H2>

<P>
You can load any LaTeX package into your document, just use the
<A HREF="userguide/Style.html">Style directive</A>. Example:
</P>

<PRE>
%!style(tex): amssymb

% The --style command line option is another alternative
</PRE>

<P>
This will create the <CODE>\usepackage{amssymb}</CODE> line on your document
Preamble. Multiple packages can be loaded in one single call:
</P>

<PRE>
%!style(tex): amssymb,booktabs,array,paralist

% Will turn into \usepackage{amssymb,booktabs,array,paralist}
</PRE>

<P>
Starting in txt2tags version 2.3.1, you can also define multiple style
calls, making it easy insert configuration for each package using
<A HREF="userguide/PostProc.html">PostProc</A> filters. Example:
</P>

<PRE>
%!style(tex): amssymb
%!style(tex): booktabs
%!style(tex): array
%!style(tex): paralist

% This will create four \usepackage lines
</PRE>

<P>
If you want to use this configuration for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="tex-date">29. LaTeX: Remove the current date</H2>

<P>
In txt2tags, the third header line is often used for the document date. If you leave it blank, no date tag will be generated. But in LaTeX, when no date tag is found, it automatically shows the current date on the document cover. Some expect this behavior, some don't.
</P>
<P>
To force the document to have no date, you must leave an empty date tag on the LaTeX code: <CODE>\date{}</CODE>. You can make it easily setting a <A HREF="userguide/PostProc.html">PostProc</A> filter:
</P>

<PRE>
%!postproc(tex): \\date{-}  \date{}
</PRE>

<P>
And in you source files, just type an hyphen on the third line, for example:
</P>

<PRE>
My doc
John Doe
-
</PRE>

<P>
The filter will remove the hyphen, leaving the tag empty and then LaTeX won't print any date.
</P>
<P>
<B>Extra tip:</B> If your TeX processor complains about the missing Author tag, you can do a similar workaround setting up another filter:
</P>

<PRE>
%!postproc(tex): \\author{-}  \author{}
</PRE>

<P>
If you want to use this configuration for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="tex-lang">30. LaTeX: Set the language config (babel, inputenc)</H2>

<P>
For the text encoding (character set) just use the <A HREF="userguide/Encoding.html">Encoding directive</A>.
Then include the babel package in your document and create a <A HREF="userguide/PostProc.html">PostProc</A>
filter to insert the language for it. It's a three line wonder:
</P>

<PRE>
% Brazilian Portuguese configuration
%!encoding: iso-8859-1
%!style(tex): babel
%!postproc(tex): {babel} [brazil]{babel}
</PRE>

<P>
This will add two extra lines to the LaTeX Preamble:
</P>

<PRE>
\usepackage[latin1]{inputenc}  % char encoding
\usepackage[brazil]{babel}  % user defined package
</PRE>

<P>
Note that the IANA standard encoding names are automatically
translated to <A HREF="userguide/Encoding.html">the LaTeX equivalents</A>
(iso-8859-1 to latin1 on this example).
</P>

<H2 ID="tex-user-style">31. LaTeX: Use a personal style file (.sty)</H2>

<P>
Create your own LaTeX user style file (say myrules.sty) with all the
packages and configuration you usually put inside the document
Preamble.
</P>
<P>
Then just use the <A HREF="userguide/Style.html">Style directive</A> pointing to your file. Remember to
include the relative path for the file, if it isn't on the same folder
as your txt2tags source file. The file must have the <CODE>.sty</CODE>
extension. You can use as many files as your heart wishes. Example:
</P>

<PRE>
%!style(tex): ../../common.sty
%!style(tex): ../../pdfthings.sty
%!style(tex): projectrules.sty
</PRE>

<P>
<B>Note:</B> The support for multiple style files was added into txt2tags
version 2.3.1.
</P>
<P>
If you want to use this configuration for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H2 ID="tex-greek">32. LaTeX: Use symbols and Greek letters (µ « ® Ø)</H2>

<P>
In LaTeX you normally just use $\mu$ to represent the µ Greek letter. You can type the letter on the txt2tags sources and make a postproc to convert it to the LaTeX entity.
</P>

<PRE>
%!postproc(tex): "µ"  "$\mu$"
</PRE>

<P>
You can create similar filters for all the Greek letters do you
normally use, as well for any other special encoded letter or symbol.
</P>
<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>

<H1 ID="text-editors">Text Editors</H1>

<H2 ID="vim-convert">33. Vim: Convert the current file</H2>

<PRE>
:!txt2tags %
</PRE>

<P>
The ! executes an external command and % expands to the current filename. Make sure you have set the <CODE>%!target</CODE> configuration on the file, so you don't have to type the <CODE>-t</CODE> option on the command line.
</P>
<P>
Note that Vim's command-line mode ":" has history, so you just have to type it once. For the next conversions just do:
</P>

<PRE>
:&lt;arrow-up&gt;
</PRE>

<P>
If you want to preserve this history even when quitting Vim, put this line in your <CODE>~/.vimrc</CODE>:
</P>

<PRE>
set viminfo='10,\"30,:40,%,n~/.viminfo
</PRE>

<H2 ID="vim-mappings">34. Vim: Handy mappings to convert files</H2>

<P>
<I>By Frank Mueller</I>
</P>
<P>
With this lines in your <CODE>~/.vimrc</CODE>, you will have handy shortcuts to convert the current file to LaTeX, HTML and text:
</P>

<PRE>
map 2l :w&lt;CR&gt;:!txt2tags -t tex % ; xelatex %&lt;.tex ; open %&lt;.pdf&lt;CR&gt;
map 2h :w&lt;CR&gt;:!txt2tags -t html % ; open %&lt;.html&lt;CR&gt;
map 2t :w&lt;CR&gt;:!txt2tags -t txt % &lt;CR&gt;
</PRE>

</div><div id="footer">
<P>
<IMG ALIGN="middle" SRC="img/t2tpowered-white.png" BORDER="0" ALT="">
</P>
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png"></a>
<P>
Last modified on 11 January 2012 at 23:16
(<A HREF="tips.t2t">See sources</A>,
<A HREF="http://validator.w3.org/check?uri=referer">Validate HTML</A>)
</P>
</div><div id="fake">
<!-- Google Analytics code -->
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-280222-14']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
</DIV>

<!-- html code generated by txt2tags 2.6.641 (http://txt2tags.org) -->
<!-- cmdline: txt2tags -t html ./tips.t2t -->
</BODY></HTML>
